Skip to main content

Transactions – TypeScript SDK Reference

Overview​

The TypeScript SDK exposes a small set of types and methods to:

  • Open a transaction session against a node
  • Build, sign (via WASM backend), and submit a transaction
  • Inspect the resulting transaction and its status/output
  • Work with smart-contract transaction payloads

This page documents those core types and methods for quick reference. Tutorials and end-to-end examples will live in separate pages.

Imports​

import {
  TransactionSession,
  createTransactionSession,
  DEFAULT_ADMIN_AUTH_GROUP,
} from "@uledgerinc/typescript-sdk";

import {
  TRANSACTION_VERSION,
  TransactionStatus,
  TransactionType,
  TransactionOutput,
  parseTransactionStatus,
  parseTransactionType,
  parseTransactionOutput,
  ULTransaction,
  ULTransactionInput,
  ULTransactionOutputData,
  ULBlock,
  InvokeContractPayload,
  UpgradeContractPayload,
  RollbackContractPayload,
} from "<your-sdk>/types/transaction";

import { Wallet, WASMBackend } from "@uledgerinc/typescript-sdk";

Replace "<your-sdk>" with your package name / path.

Transaction constants & enums​

TRANSACTION_VERSION​

export declare const TRANSACTION_VERSION = "2.0.0";

Status: TransactionStatus​

export declare enum TransactionStatus {
  Invalid = "INVALID",
  Submitted = "SUBMITTED",
  Accepted = "ACCEPTED",
  Rejected = "REJECTED"
}

Mirrors Go’s transaction.UL_TransactionStatus.

:::warning A submitted transaction is not an accepted transaction The status and output in the submit response describe the transaction as it was handed to the node. They do not confirm it. Confirm it by reading the transaction back from the node until it has a blockHeight and output is SUCCESS, or check GET {node}/blockchains/{blockchainId}/transactions/{transactionId}/status for state: "committed". A transaction the network refuses is dropped and never appears, so if it has not been confirmed within your wait window, treat it as failed and not as pending. :::

Type: TransactionType​

export declare enum TransactionType {
  Invalid = "",
  Data = "DATA",
  CreateWallet = "CREATE_WALLET",
  AlterWallet = "ALTER_WALLET",
  DeploySmartContract = "DEPLOY_SMART_CONTRACT",
  InvokeSmartContract = "INVOKE_SMART_CONTRACT",
  UpgradeSmartContract = "UPGRADE_SMART_CONTRACT",
  RollbackSmartContract = "ROLLBACK_SMART_CONTRACT"
}

Mirrors Go’s transaction.ULTransactionType.

Common values:

  • TransactionType.Data — generic data transaction
  • TransactionType.CreateWallet / TransactionType.AlterWallet — wallet-management transactions
  • TransactionType.DeploySmartContract, TransactionType.InvokeSmartContract, TransactionType.UpgradeSmartContract, TransactionType.RollbackSmartContract — smart-contract operations

Output: TransactionOutput​

export declare enum TransactionOutput {
  Invalid = "",
  ToBeProcessed = "TO_BE_PROCESSED",
  Success = "SUCCESS",
  RejectedByDuplicate = "REJECTED_BY_DUPLICATE",
  RejectedByUnexisting = "REJECTED_BY_UNEXISTING",
  RejectedByDisabled = "REJECTED_BY_DISABLED",
  RejectedByUnauthorized = "REJECTED_BY_UNAUTHORIZED",
  RejectedByInvalidSignature = "REJECTED_BY_INVALID_SIGNATURE",
  TransactionError = "TRANSACTION_ERROR"
}

Mirrors Go’s transaction.UL_TransactionOutput.

Transaction types​

VectorClock​

export type VectorClock = Record<string, number>;

Mirrors Go’s transaction.VectorClock.

Timestamp​

export interface Timestamp {
  exactTime: Date;
  approximateTime: Date;
}

Mirrors Go’s transaction.Timestamp.

ULTransactionInput​

Fields used to create a transaction:

export interface ULTransactionInput {
  blockchainId: string;
  to: string;
  from: string;
  payload: string;
  senderSignature: string;
  payloadType: TransactionType | string;
  suggestor: string;
  senderTimestamp: Date;
  payloadRoot: string;
  keyType: KeyType;
}

Mirrors Go’s transaction.ULTransactionInput.

In typical usage, many of these fields are populated during signing by the WASM backend.

ULTransactionOutputData​

Fields returned by the node:

export interface ULTransactionOutputData {
  transactionId: string;
  blockHeight: number;
  vectorClock: VectorClock;
  timestamp: Timestamp;
  version: string;
  weight: number;
  status: TransactionStatus | string;
  output: TransactionOutput | string;
  proof: string;
  proofVersion: string;
}

Mirrors Go’s transaction.ULTransactionOutput.

ULTransaction​

export interface ULTransaction extends ULTransactionInput, ULTransactionOutputData {}

Combines both input fields (what was submitted) and output fields (what the node returned), mirroring Go’s transaction.ULTransaction.

ULBlock​

export interface ULBlock {
  blockHash: string;
  previousBlockHash: string;
  height: number;
  transactions: ULTransaction[];
  merkleRoot: string;
  voters: Record<string, string>;
}

Mirrors Go’s transaction.ULBlock.

Transaction session​

Class: TransactionSession​

export declare class TransactionSession {
  constructor(nodeEndpoint: string, wallet: Wallet, backend: WASMBackend);

  initialize(): Promise<void>;

  getWallet(): Wallet;
  getNodeEndpoint(): string;
  getSuggestor(): string;

  submitTransaction(options: CreateTransactionOptions): Promise<ULTransaction>;
  submitData(options: DataTransactionOptions): Promise<ULTransaction>;
  deployContract(options: DeployContractOptions): Promise<ULTransaction>;
  invokeContract(options: InvokeContractOptions): Promise<ULTransaction>;

  upgradeContract(
    blockchainId: string,
    contractAddress: string,
    newSourceCode: string,
    reason?: string
  ): Promise<ULTransaction>;

  rollbackContract(
    blockchainId: string,
    contractAddress: string,
    targetVersion: number,
    reason?: string
  ): Promise<ULTransaction>;

  createWallet(blockchainId: string, walletData: object): Promise<ULTransaction>;
  alterWallet(blockchainId: string, targetWalletAddress: string, alterData: object): Promise<ULTransaction>;

  registerWallet(blockchainId: string, walletToRegister?: Wallet, customAuthGroups?: AuthGroups): Promise<ULTransaction>;

  getTransaction(blockchainId: string, transactionId: string): Promise<ULTransaction>;
  getBlock(blockchainId: string, height: number): Promise<any>;
}

A session encapsulates:

  • the node endpoint
  • the suggestor (node ID used for the transaction)
  • the wallet used to sign
  • the WASM backend that computes commitments/signatures

createTransactionSession​

export declare function createTransactionSession(
  nodeEndpoint: string,
  wallet: Wallet,
  backend: WASMBackend
): Promise<TransactionSession>;

Factory that returns an initialized session.

initialize()​

initialize(): Promise<void>;

Calls:

  • GET {nodeEndpoint}/health to obtain nodeId (stored as suggestor)
  • GET {nodeEndpoint}/blockchains to verify at least one blockchain exists

Session transaction submission​

submitTransaction(options)​

submitTransaction(options: CreateTransactionOptions): Promise<ULTransaction>;

Creates, signs (via WASM backend), and submits a transaction to:

POST {nodeEndpoint}/blockchains/{blockchainId}/transactions

submitData(options)​

submitData(options: DataTransactionOptions): Promise<ULTransaction>;

Convenience wrapper for TransactionType.Data. If data is an object, it is JSON-stringified before submission.

Smart contract payloads​

ContractArgs​

export interface ContractArgs {
  value: Uint8Array | string;
}

Mirrors Go’s transaction.ContractArgs.

InvokeContractPayload​

export interface InvokeContractPayload {
  functionName: string;
  args: ContractArgs[];
  gasLimit: number;
}

Mirrors Go’s transaction.InvokeContractPayload.

Used with TransactionType.InvokeSmartContract (typically JSON-encoded into ULTransactionInput.payload).

UpgradeContractPayload​

export interface UpgradeContractPayload {
  newSourceCode: string;
  upgradeReason?: string;
}

Mirrors Go’s transaction.UpgradeContractPayload.

Used with TransactionType.UpgradeSmartContract.

RollbackContractPayload​

export interface RollbackContractPayload {
  targetVersion: number;
  rollbackReason?: string;
}

Mirrors Go’s transaction.RollbackContractPayload.

Used with TransactionType.RollbackSmartContract.

Parsing helpers​

parseTransactionStatus​

export declare function parseTransactionStatus(str: string): TransactionStatus;

parseTransactionType​

export declare function parseTransactionType(str: string): TransactionType;

parseTransactionOutput​

export declare function parseTransactionOutput(str: string): TransactionOutput;

This page is intended as a reference. For step-by-step guides see our tutorial section.